<HTML><HEAD><TITLE>EplexInstance:eplex_solver_setup(+Objective, ?Cost, ++ListOfOptions, +TriggerModes)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(eplex)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>EplexInstance:eplex_solver_setup(+Objective, ?Cost, ++ListOfOptions, +TriggerModes)</H1>
Setup an external solver state for eplex instance EplexInstance
<DL>
<DT><EM>Objective</EM></DT>
<DD>Objective function: min(CostExpr) or max(CostExpr)
</DD>
<DT><EM>Cost</EM></DT>
<DD>Variable bounded by the optimal solution
</DD>
<DT><EM>ListOfOptions</EM></DT>
<DD>List of solver options
</DD>
<DT><EM>TriggerModes</EM></DT>
<DD>List of conditions for re-triggering solver
</DD>
</DL>
<H2>Description</H2>
<P>
  Setup a new external solver state for the eplex instance EplexInstance. 
  The solver state will be associated with EplexInstance;
  EplexInstance must not already have a solver state associated with it.
  This predicate allow various options to be specified when setting up the
  solver state. <TT>ListOfOptions</TT> allows a list of solver options to 
  be specified, and <TT>TriggerModes</TT> allows the 
  solver state to be set up as a demon so that the external solver is 
  automatically invoked when the conditions for re-triggering specified in
  <TT>TriggerModes</TT> are met. The external solver can also be invoked 
  explicitly via eplex_solve/1. 
</P><P>
  Declaratively, this can be seen as a compound constraint representing all
  the individual linear constraints that have been set so far and are going
  to be set up later for <TT>EplexInstance</TT>. Operationally, when the
  external solver is invoked, the delayed constraints posted to 
  <TT>EplexInstance</TT> are collected and taken into account.
</P><P>
  <TT>CostExpr</TT> is a linear cost expression (or quadratic, if supported
  by the external solver).
</P><P>
  The external solver's best objective bound will be exported as a bound
  for <TT>Cost</TT>: For a minimisation problem, each solution's best bound
  becomes a lower bound, for maximisation an upper bound on Cost.  This
  technique allows for repeated re-solving with reduced bounds or added
  constraints. Note that Cost is not automatically made a problem variable
  (it can be a problem variable if there are constraints that involve it),
  and thus may not have bounds associated with in. In order for the bounds
  information not to be lost, some bounds should be given to <TT>Cost</TT>
  (e.g. making it a problem variable (but this might introduce unnecessary
  self-waking on bounds change), or via another solver with bounds
  (e.g. ic)).
</P><P>
  <TT>ListOfOptions</TT> is the same as in the low-level primitive 
  lp_demon_setup/5, except that EplexInstance is implicitly associated with
  the new external solver state, so the <TT>collect_from</TT> option of
  lp_demon_setup/5 is not allowed (it is set to <TT>
  collect_from(pool(EplexInstance))</TT> by the predicate). See 
  below for more details.
</P><P>
  <TT>TriggerModes</TT> specifies under which conditions the external solver
  will be re-triggered. If no condition is specified, then the solver must
  be explicitly triggered, usually via eplex_solve/1. The conditions are the
  same as in the low-level primitive lp_demon_setup/5 called by this predicate.
  See below (after <TT>ListOfOptions</TT> descriptions) for more details.
</P><P>
  Note: Some external solvers need to write temporary files when they
  are solving a problem. These are written to the temporary directory
  specified in ECLiPSe's tmp_dir setting (get_flag/2, set_flag/2).

</P><P>
ListOfOptions are (such option should occur no more than once):

<DL>

<P>
<DT><STRONG><TT>initial_solve(+YesNo)</TT></STRONG>
    <DD>Specifies if an initial solve (call to the external solver) should
    be performed immediately after problem setup.
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>yes</TT> if any trigger condition is specified in TriggerModes, 
    <TT>no</TT> if no trigger condition is specified.

<P>
<DT><STRONG><TT>method(+Method)</TT></STRONG>
    <DD>Use the specified method (<TT>default, primal, dual, net,
    barrier, sifting</TT>) (representing Primal Simplex, Dual Simplex,
    Network Simplex, Barrier, and Sifting respectively) to solve the
    problem. For MIP problems, this specifies the start algorithm (the one
    that is used to solve the initial relaxation). See the external
    solver's manual for a description of these methods.
<P> 
    For some of the methods, an additional `auxiliary' method may be 
    specified in brackets. These are:
<DL>
<P>
      <DT><TT>net(Simplex)</TT>: 
      <DD>specifies the Simplex method (<TT>primal</TT> or <TT>dual</TT>) to 
      follow the network optimisation. For LP problems only.
<P>
      <DT><TT>barrier(Crossover)</TT>: 
      <DD>specifies how the crossover to a basic solution from the barrier
      solution is performed. <TT>Crossover</TT> can be <TT>primal</TT>, 
      <TT>dual</TT>, or <TT>none</TT>. <TT>none</TT> means no crossover is
      performed. 
<P>
      <DT><TT>sifting(SubMethod)</TT>: 
      <DD>specifies the method for solving the sifting subproblem. 
      <TT>SubMethod</TT> can be <TT>primal, dual, net, barrier</TT>.
<P>
</DL>
    For all the auxiliary methods, <TT>default</TT> can also be specified.
    This is equivalent to not specifying a auxiliary method at all. 
<P>
    Note that not all the methods are available on all external solvers. 
    The default method would use the solver's default method to solve the
    problem. The actual method depends on the external solver. If no method
    is specified, default is used.

<P>
<DT><STRONG><TT>node_method(+Method)</TT></STRONG>
    <DD>For MIP problems only. Use the specified method (<TT>default, primal,
    dual, net, barrier, sifting</TT>) to solve the subproblem at each node
    of the MIP search-tree, except the root node, which is specified by
    <TT>method</TT> option above. See method option for more description of
    the methods. Note that there are less choices in the specifications of
    the auxiliary methods that in the method option, due to limitations in
    the solvers. If a specified auxiliary method cannot be used, `default'
    will be used instead.

<P>
<DT><STRONG><TT>solution(+YesNo)</TT></STRONG>
    <DD>Make the solutions available each time the problem has been (re-)solved
    successfully.
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>yes</TT>.

<P>
<DT><STRONG><TT>dual_solution(+YesNo)</TT></STRONG>
    <DD>Make the dual solutions available each time the problem has been 
    (re-)solved successfully. If the problem is a MIP, then depending on
    the external solver, this is either unavailable or are the values for
    the optimal LP node. 
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>no</TT>.

<P>
<DT><STRONG><TT>slack(+YesNo)</TT></STRONG>
    <DD>Make the constraint slacks available each time the problem has been 
    (re-)solved successfully.
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>no</TT>.

<P>
<DT><STRONG><TT>reduced_cost(+YesNo)</TT></STRONG>
    <DD>Make the reduced costs available each time the problem has been 
    (re-)solved successfully. If the problem is a MIP, then depending on
    the external solver, this is either unavailable or are the values for
    the optimal LP node. 
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>no</TT>.

<P>
<DT><STRONG><TT>keep_basis(+YesNo)</TT></STRONG>
    <DD>Store the basis each time the problem has been solved successfully,
    and use this basis as a starting point for re-solving next time.
    This option only affects performance.
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>no</TT>.

<P>
    <DT><STRONG><TT>cache_iis(YesNo)</TT></STRONG>
     <DD>Specify if an IIS should be computed immediately for an infeasible problem
     (if supported by the external solver), and store it so that it can bee retrieved by
     eplex_get_iis/4 or lp_get_iis/5 (called from within a user-defined infeasible 
     handler). This will be done before the problem can be modified and make the computing 
     of the IIS impossible. The IIS will only be available before the problem is solved
     again, and also before the infeasible solve is backtracked. This option has no effect  
     if the external solver does not support the computation of an IIS. Note that if this 
     option is set, eplex will always ask for an IIS to computed for an infeasible problem, 
     even if it is immediately backtracked by the infeasible handler failing, and that the 
     option is only needed if the problem instance in the external solver is modified 
     before eplex_get_iis/4 or lp_get_iis/5 is called. 
     YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>no</TT>.

<P>
<DT><STRONG><TT>demon_tolerance(RealTol, IntTol)</TT></STRONG>
    <DD>Specify how far outside a variable's range an lp-solution
    can fall before lp_demon_setup/5 re-triggers.
    <TT>RealTol</TT> and <TT>IntTol</TT> are floats and default to
    0.00001 and 0.5 respectively.

<P>
<DT><STRONG><TT>sos1(VarList)</TT></STRONG>
    <DD><TT>VarList</TT> is a list of variables which the solver should
    treat as variables of a type 1 special ordered set (SOS), i.e. at most
    one of the variables in the set can be non-zero.

<P>
<DT><STRONG><TT>sos2(VarList)</TT></STRONG>
    <DD><TT>VarList</TT> is a list of variables which the solver should
    treat as variables of a type 2 special ordered set (SOS), i.e. at most
    two of the variables in the set can be non-zero.

<P>
<DT><STRONG><TT>presolve(+YesNo)</TT></STRONG>
    <DD>Specify if the external solver should perform presolve for this
    problem. With presolving, the external solver will transform the
    problem before solving it. This can lead to significantly faster times
    to find solutions. However, as the problem has been transformed, some
    external solvers have restriction on accessing or changing the problem
    state. In addition, if the solver is repeatedly called because the
    problem is frequently modified, then presolve may not be an advantage.
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    determined by the global setting of <TT>presolve</TT>, which can be
    changed via <TT>lp_set/2</TT>. The initial default is <TT>yes</TT>.
    Note that the presolve setting cannot be changed for a problem once it
    is set.
<P>
<DT><STRONG><TT>timeout(+TimeOut)</TT></STRONG>
    <DD>Set the external solver to time-out after <TT>TimeOut</TT> seconds.
    <TT>TimeOut</TT> is a positive number. The solver will abort (in either
    the abort or suboptimal state, depending on if a suboptimal solution
    was found) if the optimal solution was not found within the time
    limit. This should be used instead of setting the solver-specific
    parameter for time-out directly. In cases where the solver expects an
    integer for the time-out interval, the time given is rounded up to the
    next integer value. The timeout is set by setting the external
    solver's timeout settings, and the exact behaviour may be solver dependent.
<P>
<DT><STRONG><TT>suboptimal_handler(+Goal)</TT></STRONG>
    <DD>Specifies a user defined goal Goal to handle the case when the
    external solver returned a suboptimal solution (because the problem
    was aborted). Goal would be run in place of raising the default 
    <TT>eplex_suboptimal</TT> event.
<P>
<DT><STRONG><TT>unbounded_handler(+Goal)</TT></STRONG>
    <DD>Specifies a user defined goal Goal to handle the case when the
    problem is unbounded. Goal would be run in place of raising the  
    default <TT>eplex_unbounded</TT> event.
<P>
<DT><STRONG><TT>infeasible_handler(+Goal)</TT></STRONG>
    <DD>Specifies a user defined goal Goal to handle the case when the
    external solver found that the problem is infeasible. Goal would be run
    in place of raising the default <TT>eplex_infeasible</TT> event.  Note
    that the default and logically correct behaviour is to fail, this
    handler is provided to allow the user to analyse the cause of the
    infeasibility. It is recommended that the handler should also fail
    after performing the analysis.
<P>
<DT><STRONG><TT>unknown_handler(+Goal)</TT></STRONG>
    <DD>Specifies a user defined goal Goal to handle the case when the
    external solver was not able to determine if the problem is unbounded
    or infeasible. Goal would be run in place of raising the default 
    <TT>eplex_unknown</TT> event.
<P>
<DT><STRONG><TT>abort_handler(+Goal)</TT></STRONG>
    <DD>Specifies a user defined goal Goal to handle the case when the
    external solver aborted without finding any solution. Goal would be 
    run in place of raising the default <TT>eplex_abort</TT> event.
<P>
<DT><STRONG><TT>use_var_names(+YesNo)</TT></STRONG>
    <DD>Specify if variable names (set using <TT>set_var_name/2</TT> of the 
    var_name library) should be passed to the external solver. If a 
    particular variable does not have a name, a solver's default name 
    would be used. Note that for XPRESS-MP, there is a limit on the length
    of the name, which can be changed between 8 and 64 in steps of 8 with
    the parameter <TT>mpsnamelength (XPRS_MPSNAMELENGTH)</TT>. Variable 
    names longer than this limit are truncated to the limit. 
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>no</TT>.
<P>
<DT><STRONG><TT>priority(+Prio)</TT></STRONG>
  <DD><TT>Prio</TT> is the scheduling priority with which the solver gets
  woken up.  This priority determines whether the solver is run before or
  after other constraints. By default, if no priority is specified, the
  default priority (0, mapped to 5 unless changed) is used. Normally, the
  default priority should be sufficient and this option is not needed,
  unless there is a specific need to have the external solver invoked with
  higher or lower priority than some other constraints.
<P>
<DT><STRONG><TT>mip_use_copy(+YesNo)</TT></STRONG>
    <DD>Some external solvers do not allow a MIP problem to be modified
    once the MIP search has been started. Eplex works around this
    problem by making a copy of the problem and solving that, so that
    the original problem can still be modified. This can be turned off to
    avoid the overhead of making this copy, in which case the MIP
    problem cannot be modified. This option is used only when solving a
    MIP problem, and the external solver does not allow a MIP problem to
    be modified; otherwise it is ignored.
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default 
    is <TT>yes</TT> so that the problem can be modified.
<P>
<DT><STRONG><TT>write_before_solve(+Format,+File)</TT></STRONG>
    <DD>This option is most useful for debugging purposes. If given, Eplex
    will ask the external solver to dump the problem each time the problem
    is solved. This allows the problem in an <TT>eplex_probe/2</TT> or
    <TT>lp_probe/3</TT> to be dumped. As in <TT>lp_write/3</TT>,
    <TT>Format</TT> is the format of the dumped file and <TT>File</TT> is
    its name. Note that the problem is dumped each time the external solver
    is invoked if the problem has cutpool constraints, where there may be
    multiple invocations of the solver per solver call. 
    The default without this option is that the problem would not be dumped.
<P>
<DT><STRONG><TT>post_equality_when_unified(+YesNo)</TT></STRONG>
    <DD>This option determines if an equality constraint between two
    variables will be posted to the solver when these variables are
    unified. Setting <TT>YesNo</TT> to no means that the constraint 
    will <EM>not</EM> be posted. Note that this can lead to the
    solver's problem becoming inconsistent with ECLiPSe's. 
    YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 
    <TT>yes</TT>.
<P>
<DT><STRONG><TT>sync_bounds(+YesNo)</TT></STRONG>
    <DD>This option determines if the bounds of the problems variables are
    synchronised with other solvers (i.e. the generic bounds are obtained
    with get_var_bounds/3 and then passed to the external solver) before
    the external solver is invoked. This was always done for previous
    non-standalone version of eplex. For standalone eplex, as the bounds
    are communicated directly to the external solver, the synchronisation
    of variable bounds is not needed unless the user is using eplex
    co-operatively with other solvers (e.g. ic). Even in such cases, it may
    be more efficient to communicate these bounds changes by explicitly
    programming it, especially if the problem has many variables and bounds
    changes happen only to a few of the variables. Setting <TT>YesNo</TT>
    to yes should increase compatibility with previous code (but note that
    previous eplex obtained the bounds from a specific bounds keeper like
    ic rather than the generic bounds).  YesNo is one of the atoms
    <TT>yes</TT> or <TT>no</TT>, the default is <TT>no</TT>.

</DL>
<P>
<TT>TriggerModes</TT> can be a list of the following specifiers:

<DL>

  <DT><STRONG><TT>inst</TT></STRONG>
  <DD>re-trigger if a problem variable gets instantiated.

  <DT><STRONG><TT>ModuleName:Index</TT></STRONG>
  <DD>re-trigger when the  suspension list given by ModuleName:Index is woken
  for any of the problem variables.
  The format for <TT>ModuleName:Index</TT> is the same as for specifying
  the suspension list in suspend/3,4.

  <DT><STRONG><TT>deviating_inst</TT></STRONG>
  <DD>re-trigger if a problem variable gets instantiated
      to a value that differs from its lp-solution more than a tolerance.

  <DT><STRONG><TT>bounds</TT></STRONG>
  <DD>re-trigger each time a variable bound for the solver instance changes.

  <DT><STRONG><TT>deviating_bounds</TT></STRONG>
  <DD>re-trigger each time a variable's solver instance bound changes
      such that its lp-solution gets excluded more than a tolerance.

  <DT><STRONG><TT>new_constraint</TT></STRONG>
  <DD>re-trigger each time a new (arithmetic or integral) constraint is
      added to the solver instance. Note that adding integral constraint
      on new problem variables, or adding bounds constraint, or adding 
      constraints to the cutpool will *not* re-trigger.

  <DT><STRONG><TT>trigger(Atom)</TT></STRONG>
  <DD>re-trigger each time the symbolic trigger Atom is pulled by invoking 
      schedule_suspensions/1

  <DT><STRONG><TT>pre(Goal)</TT></STRONG>
  <DD>an additional condition to be used together with other triggers. When 
      the demon is triggered, it first executes <TT>PreGoal</TT>. Only if 
      that succeeds, does the appropriate external solver get invoked.
      This provides a way of reducing the number of (possibly expensive)
      solver invocations when given preconditions are not met.

  <DT><STRONG><TT>post(Goal)</TT></STRONG>
  <DD>this is not a trigger condition, but specifies a goal to be executed
      after solver success, but before the Cost variable gets
      constrained. It is intended as a hook for exporting solution
      information, e.g. copying solutions from the solver state into
      variable attributes (eg. tentative value), or computing weights for
      labelling heuristics from the solver state.  
  <DT><STRONG><TT>suspension(Susp)</TT></STRONG>
  <DD>this is not a trigger condition, but instead is used to access the 
      demon used to trigger the solver. Susp is instantiated to
      the suspension that triggers the solver: by waking Susp, the solver
      is triggered. Susp is a demon in that it stays around after being
      woken. Accessing Susp allows the user to specify orbitally conditions 
      for triggering the solver.
</DL>

  The tolerances mentioned can be specified in lp_setup/4 or lp_set/3
  as <TT>demon_tolerance</TT>.

</P><P>
  If several trigger conditions are specified, then any of them will trigger
  the solver.

</P><P>
  When a solver demon runs frequently on relatively small problems,
  it can be important for efficiency to switch off the presolve option
  to reduce overheads.

</P>
<H2>See Also</H2>
<A HREF="../../lib/eplex/SE-2.html">$= / 2</A>, <A HREF="../../lib/eplex/SEL-2.html">$=< / 2</A>, <A HREF="../../lib/eplex/SGE-2.html">$>= / 2</A>, <A HREF="../../lib/eplex/ENE-2.html">=:= / 2</A>, <A HREF="../../lib/eplex/GE-2.html">>= / 2</A>, <A HREF="../../lib/eplex/EL-2.html">=< / 2</A>, <A HREF="../../lib/eplex/SNN-2.html">$:: / 2</A>, <A HREF="../../lib/eplex/NN-2.html">:: / 2</A>, <A HREF="../../lib/eplex/integers-1.html">integers / 1</A>, <A HREF="../../lib/eplex/reals-1.html">reals / 1</A>, <A HREF="../../lib/eplex/eplex_solver_setup-1.html">eplex_solver_setup / 1</A>, <A HREF="../../lib/eplex/eplex_probe-2.html">eplex_probe / 2</A>, <A HREF="../../lib/eplex/eplex_solve-1.html">eplex_solve / 1</A>, <A HREF="../../lib/eplex/eplex_get-2.html">eplex_get / 2</A>, <A HREF="../../lib/eplex/eplex_var_get-3.html">eplex_var_get / 3</A>, <A HREF="../../lib/eplex/eplex_get_iis-4.html">eplex_get_iis / 4</A>, <A HREF="../../lib/eplex/lp_demon_setup-5.html">lp_demon_setup / 5</A>, <A HREF="../../lib/eplex/lp_setup-4.html">lp_setup / 4</A>
</BODY></HTML>
